﻿//	Plazes-ASPI is an AS2.0 abstraction of the Plazes (http://www.plazes.com) XMLRPC-API
//		Copyright (C) 2006	Florian Mlodzik
//
//		This library is free software; you can redistribute it and/or
//		modify it under the terms of the GNU Lesser General Public
//		License as published by the Free Software Foundation; either
//		version 2.1 of the License, or (at your option) any later version.
//
//		This library is distributed in the hope that it will be useful,
//		but WITHOUT ANY WARRANTY; without even the implied warranty of
//		MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	See the GNU
//		Lesser General Public License for more details.
//
//		You should have received a copy of the GNU Lesser General Public
//		License along with this library; if not, write to the Free Software
//		Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

// svn:keywords
// $URL: http://plazes-aspi.googlecode.com/svn/trunk/src/as2/com/orthogeneric/webapis/plazes/PlazesService.as $
// $Id: PlazesService.as 5 2006-08-07 19:54:11Z florian.mlodzik $

/**
* The PlazesService represents an Actionscript2 abstraction of the <a href="http://api.plazes.com/">PlazesApi</a>.
* Methods provided by the API are organized like object methods ("object.method") which are hereby defined as "groups".
* API-groups are up to this version (PlazesApi 1.0) "plaze", "user" and "api" which can all be accessed from a PlazesService-instance with their corresponding methods through the member variables {@link #plaze}, {@link #user} and {@link #api}.
* Calling a group's method will automagically invoke a remote procedure call, receive the result, serialize it to Actionscript datatypes and make it available through a dispatched {@link PlazesResult PlazesResult}'s {@code result} property. A {@link com.orthogeneric.webapis.plazes.events.PlazesFault PlazesFault} and a {@link com.orthogeneric.webapis.plazes.events.PlazesError PlazesError} will be	dispatched upon receival of according RPC-responses.
* 
* <b>Compatibility:</b> 
* Compiles with Adobe Flash MX 2004 IDE, Adobe Flash 8 IDE and <a href="http://www.mtasc.org/">MotionTwin</a> 1.12
* Adobe FlashPlayer 6.0.79 to 8.0.22
* 
* @author florian.mlodzik@gmail.com
* @version 1.0a
* @use	Example 1 (override event handlers):
* 			<code>
* 			var ps:PlazesService = new PlazesService("myDevKey", "myUN", "myPW");
* 					ps.onPlazesResult = function (evt:PlazesResult)
* 					{
* 						trace("Result received from remote method: "+evt.remoteMethod);
* 						if (evt.localMethod == "getVersion") {
* 							trace("PlazesApi version is "+evt.result);
* 						}
* 					}
* 					ps.onPlazesFault = function (evt:PlazesFault)
* 					{
* 						trace("Fault received from remote method: "+evt.remoteMethod);
* 					}
* 					ps.onPlazesError = function (evt:PlazesError)
* 					{
* 						trace("Error occurred while trying to call remote method: "+evt.remoteMethod);
* 					}
* 					ps.user.getTrazes(90);
* 					ps.api.getVersion();
* 			</code>
* 			 
* 			Example 2 (add listener to event/queue remote calls):
* 			<code>
* 			var resultListener:Object = new Object();
* 					resultListener.onPlazesResult = function (evt:PlazesResult)
* 					{
* 						trace("Result received from remote method: "+evt.remoteMethod);
* 						if (evt.localMethod == "getVersion") {
* 							trace("PlazesApi version is "+evt.result);
* 						}
* 					}
* 			var ps:PlazesService = new PlazesService("myDevKey", "myUN", "myPW", true);
* 					ps.addEventListener("onPlazesResult", resultListener);
* 					ps.user.getTrazes(90);
* 					ps.api.getVersion();
* 			</code>
* @see <a href="http://www.plazes.com">Plazes</a>
* @see <a href="http://api.plazes.com/wiki/index.php/Plazes_API_Documentation" target="_blank">PlazesApi documenation</a>
*/

// import -->
import mx.events.EventDispatcher;
import com.orthogeneric.util.MD5;
import com.orthogeneric.webapis.plazes.rpc.RPCall;
import com.orthogeneric.webapis.plazes.methods.PlazeMethods;
import com.orthogeneric.webapis.plazes.methods.UserMethods;
import com.orthogeneric.webapis.plazes.methods.ApiMethods;
import com.orthogeneric.webapis.plazes.events.PlazesResult;
import com.orthogeneric.webapis.plazes.events.PlazesFault;
import com.orthogeneric.webapis.plazes.events.PlazesError;
// <-- import

class com.orthogeneric.webapis.plazes.PlazesService 
{
	// The URI of the plazes XMLRPC-interface
	private static var _ENDPOINT_:String = "http://beta.plazes.com/api/plazes/xmlrpc";
	// A string concatenated with the user password as key for MD5 calculation
	private static var _MD5SALT_:String = "PLAZES";
	
	/** The developer key used for your application */
	public var devKey:String;
	/** The plazes-login username */
	public var username:String;
	
	// The plazes-login password in clear text
	private var _password:String;
	// The MD5-string generated from [_password + _MD5SALT_] as actual plazes-login password 
	private var _passwordMD5:String;
	// An instance of the methods.PlazeMethods-class
	private var _plazeMethods:PlazeMethods;
	// An instance of the methods.UserMethods-class
	private var _userMethods:UserMethods;
	// An instance of the methods.ApiMethods-class
	private var _apiMethods:ApiMethods;
	
	/**
	* The PlazesService-class constructor.
	* 
	* @param	dKey (optional) The needed developer key for this application
	* @param	uname (optional) The plazes-login username
	* @param	passwd (optional) The plazes-login clear text password
	* @param	qCalls (optional) The boolean whether to process requests sequentially. Default is {@code false}. 			 									
	*/
	public function PlazesService(dKey:String, uname:String, passwd:String, qCalls:Boolean)
	{
		// init instance variables
		devKey = dKey != undefined ? dKey : "";
		username = uname != undefined ? uname : "";
		password = passwd != undefined ? passwd : "";
		queueCalls = qCalls != undefined ? qCalls : false;
		
		_plazeMethods = new PlazeMethods(this);
		_userMethods = new UserMethods(this);
		_apiMethods = new ApiMethods(this);
		
		// initialize this to become an EventDispatcher
		EventDispatcher.initialize(this);
		// add this as listener to self for overriding the response methods
		addEventListener("onPlazesResult", this);
		addEventListener("onPlazesFault", this);
		addEventListener("onPlazesError", this);	
	}
	
	/**
	* The URI of the plazes XMLRPC-interface
	* Implemented as getter function.
	* 
	*/
	public static function get ENDPOINT():String
	{
		return _ENDPOINT_;	
	}
	
	/**
	* The instance-variable holding/storing the password in clear text.
	* Implemented as getter/setter function.
	* 
	* @see com.orthogeneric.webapis.plazes.PlazesService#passwordMD5
	*/
	public function get password():String
	{
		return _password;  
	}
	public function set password(pw:String):Void
	{
		_password = pw;
		_passwordMD5 = pw.toString() != "" && pw != undefined ? MD5.calculateHex(_MD5SALT_ + pw) : "";	
	}
	
	/**
	* The instance-variable depicting whether remote calls shall be invoked sequentially.
	* "Queueing" means here that the invocation of a remote method will be delayed until all previously instigated calls have received a response (result, fault or error).
	* Implemented as getter/setter function.
	* 
	*/
	public function get queueCalls():Boolean 
	{
		return RPCall.queue;	
	}
	public function set queueCalls(q:Boolean):Void 
	{
		RPCall.queue = q;  
	}
	
	/**
	* The instance-variable to gain access to remote methods related to a "plaze".
	* Implemented as getter function.
	* 
	* @return The composited PlazeMethods-instance 
	* @see com.orthogeneric.webapis.plazes.methods.PlazeMethods
	*/
	public function get plaze():PlazeMethods
	{
		return _plazeMethods;  
	}
	
	/**
	* The instance-variable to gain access to remote methods related to a "user".
	* Implemented as getter function.
	* 
	* @return The composited UserMethods-instance 
	* @see com.orthogeneric.webapis.plazes.methods.UserMethods
	*/
	public function get user():UserMethods
	{
		return _userMethods;	
	}
	
	/**
	* The instance-variable to gain access to remote methods related to the "api".
	* Implemented as getter function.
	* 
	* @return The composited ApiMethods-instance 
	* @see com.orthogeneric.webapis.plazes.methods.ApiMethods
	*/
	public function get api():ApiMethods
	{
		return _apiMethods;  
	}
	
	/**
	* The instance-variable holding the MD5-password used for actual log in.
	* Implemented as getter/setter function.
	* 
	* Note: Setting a MD5-password using this setter function will set {@link password} to an empty string.
	* 
	* @see com.orthogeneric.webapis.plazes.PlazesService#password
	*/
	public function get passwordMD5():String
	{
		return _passwordMD5;	
	}
	public function set passwordMD5(pw:String):Void
	{
		_password = "";
		_passwordMD5 = pw;	
	}
	/**
	* The instance-method to register an object as a listener to an event dispatched by this PlazesService-instance.
	* Available events are:
	* 
	* 	"onPlazesResult" - dispatched when a result from a remote method has been received
	* 	"onPlazesFault" - dispatched when the remote method returned a fault (i.e. failed login)
	* 	"onPlazesError" - dispatched when an error (i.e. api is not available) has occurred
	* 
	*/
	public function addEventListener(event:String, listener:Object):Void
	{
	}
	
	/**
	* The instance-method to un-register an object as a listener to an event dispatched by this PlazesService-instance.
	* 
	* @see #addEventListener() 
	*/
	public function removeEventListener(event:String, listener:Object):Void
	{
	}
	
	/**
	* The instance-method to dispatch an event by this PlazesService-instance to all registered listeners.
	* The passed object should be of types PlazesResult, PlazesFault or PlazesError.
	* 
	* @see com.orthogeneric.webapis.plazes.events.PlazesResult 
	* @see com.orthogeneric.webapis.plazes.events.PlazesFault
	* @see com.orthogeneric.webapis.plazes.events.PlazesError
	* @exclude
	*/
	public function dispatchEvent(evt:Object):Void
	{
	}
	
	/**
	* The instance-method that is being invoked when a result has been received as the rpc-response
	* 
	* @see com.orthogeneric.webapis.plazes.events.PlazesResult 
	*/
	public function onPlazesResult(evt:PlazesResult):Void
	{
	}
	
	/**
	* The instance-method that is being invoked when a fault has been received as the rpc-response
	* 
	* @see com.orthogeneric.webapis.plazes.events.PlazesFault 
	*/
	public function onPlazesFault(evt:PlazesFault):Void
	{
	}
	
	/**
	* The instance-method that is being invoked when an error occured during a rpc
	* 
	* @see com.orthogeneric.webapis.plazes.events.PlazesError 
	*/
	public function onPlazesError(evt:PlazesError):Void
	{
	}
}